home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / Tools / Mesa-1.2.1 / README < prev   
Encoding:
Text File  |  1995-07-05  |  15.4 KB  |  449 lines
  1.  
  2.               The Mesa 3-D graphics library
  3.  
  4.                   Version 1.2.1
  5.  
  6.               Copyright (C) 1995  Brian Paul
  7.  
  8.  
  9.  
  10. Introduction
  11. ============
  12.  
  13. Mesa is a 3-D graphics library with an API which is very similar to that
  14. of OpenGL*.  To the extent that Mesa utilizes the OpenGL command syntax
  15. or state machine, it is being used with authorization from Silicon Graphics,
  16. Inc.  However, the author makes no claim that Mesa is in any way a
  17. compatible replacement for OpenGL or associated with Silicon Graphics, Inc.
  18. Those who want a licensed implementation of OpenGL should contact a licensed
  19. vendor.  This software is distributed under the terms of the GNU Library
  20. General Public License, see the LICENSE file for details.
  21.  
  22. * OpenGL(R) is a registered trademark of Silicon Graphics, Inc.
  23.  
  24.  
  25.  
  26. Author
  27. ======
  28.  
  29. Brian Paul
  30. Space Science and Engineering Center
  31. University of Wisconsin - Madison
  32. 1225 W. Dayton St.
  33. Madison, WI  53706
  34.  
  35. brianp@ssec.wisc.edu
  36.  
  37.  
  38.  
  39. Status
  40. ======
  41.  
  42. I've been working on this library in my spare time since August, 1993.
  43. It's currently about 90% complete.  You'll find that most programs which
  44. use the OpenGL tk, aux or GLUT toolkits will work with Mesa without changing
  45. the source code at all.
  46.  
  47. Features which are complete:
  48.     all glBegin() primitives
  49.     all model and view transformations
  50.     clipping (against user clip planes and view volume)
  51.     lighting
  52.     smooth shading
  53.     depth buffering
  54.     accumulation buffer
  55.     alpha testing/blending
  56.     stencil buffer
  57.     dithering
  58.     logic operations
  59.     evaluators  (curves and surfaces)
  60.     feedback/selection
  61.     fog (per-pixel or per-vertex)
  62.     polygon/line stippling
  63.     read/write/copy pixels
  64.     tk and aux libraries for X11
  65.     context switching (multiple windows)
  66.     RGB mode simulated in color mapped windows
  67.     the GLX library (as close as I can get)
  68.  
  69. Features which are mostly complete:
  70.     display lists
  71.     texture mapping
  72.     the GLU library
  73.  
  74. Missing features:
  75.     anti-aliasing
  76.     mipmapping, non-point-sampled texture mapping
  77.     NURBS
  78.     glPixelZoom
  79.  
  80. The primary goal of this library has been correctness, speed was secondary
  81. (but not neglected!).  Many optimizations can still be done.
  82.  
  83. The core library was originally written on an Amiga using the DCC compiler.
  84. Later on it was moved to an SGI.  Current development is done on an SGI
  85. system.
  86.  
  87. Mesa works on most Unix workstations with ANSI C and X11.  Now there's also
  88. a Microsoft Windows driver (see windows/README.WIN).  A very outdated and
  89. inoperative Amiga driver is also included.
  90.  
  91. While a 24-bit TrueColor display is recommended for RGB mode rendering,
  92. the Mesa/X driver supports rendering on 8-bit and even 1-bit displays by
  93. dithering.
  94.  
  95. Please send bug reports to the author.  Include information describing
  96. your system, which version of Mesa you're using, and how to reproduce the
  97. problem.  Bug fixes are especially welcome.  Note that some parts of Mesa
  98. (widgets, GLU tesselator, GLE library, etc) were contributed by others and
  99. any bugs in those components should be sent to the respective author.
  100.  
  101.  
  102.  
  103. Manifest
  104. ========
  105.  
  106. The archive file Mesa-1.2.1.tar.Z can be unpacked with:
  107.     zcat Mesa-1.2.1.tar.Z | tar xvf -
  108.  
  109. After you unpacking you should have the following:
  110.  
  111. Mesa/README        - this file
  112. Mesa/LICENSE        - the GNU library license
  113. Mesa/Makefile        - top-level Makefile
  114. Mesa/Make-config    - system configurations used by the Makefiles
  115. Mesa/include/        - application include files
  116. Mesa/lib/        - application libraries, directory created by make
  117. Mesa/src/        - source code for core library
  118. Mesa/src-glu/        - source code for utility library
  119. Mesa/src-tk/        - source code for tk library
  120. Mesa/src-aux/        - source code for aux library
  121. Mesa/demos/        - demo programs
  122. Mesa/samples/        - sample OpenGL programs from SGI
  123. Mesa/book/        - example programs from the OpenGL Programming Guide
  124. Mesa/GLUT/        - the home for GLUT
  125. Mesa/widgets/        - the Mesa widgets
  126. Mesa/contrib/        - user contributed software
  127. Mesa/windows/        - Microsoft Windows driver stuff
  128.  
  129.  
  130. Installation for Unix/X11
  131. =========================
  132.  
  133. To compile the library, first type 'make' alone to see the list of system
  134. configurations currently supported.  If you see your configuration on the
  135. list, type 'make <system>'.  Most popular Unix/X workstations are currently
  136. supported.
  137.  
  138. The top-level makefile will execute the makefiles in a number of sub-
  139. directories.  When finished, there should be executables in the "demos/",
  140. "samples/", and "book/" directories for you to try out.
  141.  
  142. If your system is not listed by 'make', you'll have to modify the top-level
  143. Makefile and Make-config files.  There are instructions in each file.
  144.  
  145. If you have compilation problems you should try to fix them and return the
  146. patches to the author.
  147.  
  148. The file src/config.h has many parameters which you can tune before building.
  149.  
  150. If you want to build the Mesa widgets read the widgets/INSTALL file.
  151.  
  152. If you want to build the GLUT library read the GLUT/README-MESA file.
  153.  
  154.  
  155.  
  156. Installation for Microsoft Windows
  157. ==================================
  158.  
  159. See the windows/README.WIN file for details.  Note that any problems with
  160. the Windows driver should be addressed to Mark Peterson.  Also, be aware
  161. that this is a preliminary release of the Windows driver; there are prob-
  162. ably bugs.
  163.  
  164.  
  165.  
  166. Using the library (with Unix/X11 systems)
  167. =========================================
  168.  
  169. To use the library with your own applications you may want to move the
  170. files in "include/" to "/usr/local/include/" and the libraries in "lib/"
  171. to "/usr/local/lib/".  Then compile your graphics application with
  172. "-I/usr/local/include" and link with "-L/usr/local/lib -lMesaGL -lMesaGLU",
  173. for example.  Look at the demos/Makefile for an example.
  174.  
  175. Since the OpenGL API is used, OpenGL documentation can serve as the
  176. documentation for Mesa's core functions.
  177.  
  178. Initially, you may write your own Mesa programs using the aux or tk tool-
  179. kits which are used in the OpenGL Programming Guide and in SGI's demos,
  180. respectively.  However, these toolkits weren't meant for use in real app-
  181. lications.  You have several alternatives:
  182.  
  183. 1. Go directly to the X/Mesa interface using the functions described in
  184. include/GL/xmesa.h.  This requires experience with X programming.
  185.  
  186. 2. Use the GLX (simulated since Mesa doesn't implement the GLX extension)
  187. functions.  These functions look like, and try to act like, the real GLX
  188. functions used by OpenGL in conjunction with the X window system.
  189.  
  190. 3. GLUT (OpenGL Utility Toolkit) was written by Mark Kilgard at SGI as
  191. a replacement for aux and tk.  It provides a simple, portable, window-
  192. system independent interface allowing you to write OpenGL applications
  193. quickly and easily.  GLUT isn't included with Mesa but you'll find instruc-
  194. tions on how to get and build GLUT in the file GLUT/README-MESA.
  195.  
  196. 4. Use a Mesa widgets.  Look in the widgets/ directory for more info.
  197.  
  198.  
  199. A few tips on getting the best performance from Mesa:
  200.  
  201. 1. Turn off smooth shading when you don't need it (glShadeModel)
  202. 2. Turn off depth buffering when you don't need it.
  203. 3. Use double buffering as it's often faster than single buffering
  204. 4. Compile in the X Shared Memory extension option if it's supported
  205.    on your system by adding -DSHM to CFLAGS and -lXext to XLIBS for
  206.    your system in the Make-config file.
  207. 5. Recompile Mesa with more optimization if possible.
  208. 6. Try to maximize the amount of drawing done between glBegin/glEnd pairs.
  209. 7. Use the MESA_BACK_BUFFER variable to find best performance in double
  210.    buffered mode.
  211.  
  212.  
  213. Debugging:  normally Mesa records but does not notify the user of errors.
  214. It is up to the application to call glGetError to check for errors.  Mesa
  215. supports an environment variable, MESA_DEBUG, to help with debugging.  If
  216. MESA_DEBUG is defined, a message will be printed to stdout when an error
  217. occurs.
  218.  
  219.  
  220. Display Modes:  The glXChooseVisual function tries its best to pick an
  221. appropriate visual for the given attribute list.  However, if this doesn't
  222. suit your needs you can force Mesa to use any X visual you want (though not
  223. all are supported) by setting the MESA_RGB_VISUAL and MESA_CI_VISUAL envi-
  224. ronment variables.  When an RGB visual is requested, glXChooseVisual will
  225. first look if the MESA_RGB_VISUAL variable is defined.  If so, it will try
  226. to use the specified visual.  Similarly, when a color index visual is re-
  227. quested, glXChooseVisual will look for the MESA_CI_VISUAL variable.
  228.  
  229. The format of accepted values is:  <visual-class> <depth>
  230. Here are some examples:
  231.  
  232. using the C-shell:
  233.     % setenv MESA_RGB_VISUAL "TrueColor 8"        // 8-bit TrueColor
  234.     % setenv MESA_CI_VISUAL "PseudoColor 12"    // 12-bit PseudoColor
  235.     % setenv MESA_RGB_VISUAL "PseudoColor 8"    // 8-bit PseudoColor
  236.  
  237. using the KornShell:
  238.     $ export MESA_RGB_VISUAL="TrueColor 8"
  239.     $ export MESA_CI_VISUAL="PseudoColor 12"
  240.     $ export MESA_RGB_VISUAL="PseudoColor 8"
  241.  
  242.  
  243. Another environment variable, MESA_BACK_BUFFER, controls whether the back
  244. buffer (for double buffering) is implemented using an X Pixmap or XImage.
  245. A pixmap is faster when drawing simple lines and polygons while an XImage
  246. is faster when Mesa has to do pixel-by-pixel rendering.  Using the
  247. MESA_BACK_BUFFER variable you can experiment to see which is faster for
  248. your application.  The valid values for MESA_BACK_BUFFER are:  Pixmap and
  249. XImage (only the first letter is checked, case doesn't matter).
  250.  
  251.  
  252. While Mesa includes its own header files GL/gl.h GL/glx.h GL/glu.h you can
  253. optionally compile Mesa using the real OpenGL header files if you have
  254. them.  Just remove or move the GL/gl.h GL/glx.h GL/glu.h Mesa files and
  255. replace them with copies or links to the real OpenGL header files.  Then
  256. recompile Mesa.
  257.  
  258.  
  259.  
  260. Miscellaneous
  261. =============
  262.  
  263. See the src/NOTES file for more detailed info about the implementation
  264. of Mesa.  See the book/NOTES and samples/NOTES files for information
  265. about which demos work or don't work, and why.
  266.  
  267. The latest version of Mesa can be found at iris.ssec.wisc.edu in pub/misc/
  268.  
  269. There is a Mesa WWW page:  http://www.ssec.wisc.edu/~brianp/Mesa.html
  270.  
  271. There is a Mesa mailing list.  To subscribe, send the following message to
  272. the address listserv@iqm.unicamp.br
  273.  
  274. subs mesa <your name>
  275. set mesa mail ack
  276.  
  277. For example:
  278.  
  279. subs mesa Brian Paul
  280. set mesa mail ack
  281.  
  282. The second line tells the list processor to send you a copy of your own
  283. messages.
  284.  
  285. You will receive a welcome message from the list server when you have been
  286. added to the list.  It tells you how to post messages to the list, how
  287. to unsubscribe, etc.  Thanks to Pedro Vazquez for setting up the list.
  288.  
  289. There is a contrib/ subdirectory containing contributions from Mesa users.
  290. See the README file in that directory for more information.
  291.  
  292.  
  293.  
  294. Known Bugs
  295. ==========
  296.  
  297. Polygons with two nearly-co-located vertices may be mis-rendered or acciden-
  298. tally culled.
  299.  
  300. Perspective-corrected texture map coordinate interpolation can fail under
  301. certain conditions due to numerical error.
  302.  
  303.  
  304.  
  305. Version History
  306. ===============
  307.  
  308. 1.0 beta   February 1995
  309.     Initial release
  310.  
  311. 1.1 beta   March 4, 1995
  312.     Many improvements:
  313.     - faster point and line drawing (2x faster)
  314.     - more systems supported, better Makefiles
  315.     - many small bug fixes
  316.     - pseudo-GLX functions added
  317.     - GLUT support
  318.     - new implementation of evaluators (eval2.c)
  319.     - Renamed lib*.a files to avoid collisions
  320.  
  321. 1.1.1 beta   March 7, 1995
  322.     Reverted from eval2.c to eval.c due to FPE on Linux
  323.     more speed improvements
  324.     more Makefile changes
  325.  
  326. 1.1.2 beta   March 14,1995
  327.     Using eval2.c again
  328.     more FPE-prevention checks (0-length normals are OK)
  329.     a few small bug fixes
  330.     much faster pixel logic ops!
  331.     faster transformation arithmetic
  332.     implementation of SGI's blending extensions
  333.     glXUseXFont implemented
  334.     added MESA_DEBUG environment variable support
  335.  
  336. 1.1.3 beta   March 31,1995
  337.     gluScaleImage() and gluBuild2DMipMaps() implemented
  338.     Mesa widgets for Xt/Motif
  339.     more bug fixes
  340.     blendEXT demos
  341.     added environment variables for selecting visuals
  342.     almost all GLUT demos work correctly now
  343.     faster X device driver functions
  344.  
  345. 1.1.4 beta   April 20,1995
  346.     Bug fixes:
  347.     - missing #define SEEK_SET in src-tk/image.c
  348.     - compile glShadeModel into display lists
  349.     - fixed pow() domain error in src/light.c
  350.     - fixed "flickering bitmaps" in double buffer mode
  351.     - fixed tk.h and aux.h for C++
  352.     - state of LIGHT_MODEL_LOCAL_VIEWER was inverted
  353.     New features:
  354.     - MUCH, MUCH nicer dithering in 8-bit RGB mode
  355.     - updated widgets and widget demos
  356.     - Implemented GLXPixmap functions
  357.     - Added GLU 1.1 and GLX 1.1 functions
  358.     - Changed the X/Mesa interface API, more versatile
  359.     - Implemented gluPartialDisk()
  360.  
  361. 1.2   May 22,1995
  362.     Bug fixes:
  363.     - IRIX 4.x makefile problem
  364.     - modified tk to share root colormap as needed
  365.     - gluLookAt normalization problem
  366.     - suppress Expose, NoExpose events in swapbuffers
  367.     - glBitmap() and glDrawPixels() clipping
  368.     New features:
  369.     - GL_BLEND, GL_MODULATE, GL_DECAL, and GL_REPLACE_EXT texture
  370.           modes implemented
  371.     - texture maps stored more efficiently
  372.     - texture maps can be compiled into display lists
  373.     - Bogdan Sikorski's GLU polygon tesselation code
  374.     - Linas Vepstas's sweep and extrusion library
  375.     - glXCreateContext()'s shareList parameter works as it's supposed to.
  376.           XMesaCreateContext() updated to accept a shareList parameter too.
  377.     - Mesa can be compiled with real OpenGL .h files
  378.     - MESA_BACK_BUFFER environment variable
  379.     - better GLX error checking
  380.  
  381. 1.2.1   June 22, 1995
  382.     Bug fixes:
  383.     - X/Mesa double buffer window resize crash
  384.     - widgets now pass PointerMotion events
  385.     - X/Mesa incorrect default clear color and drawing color
  386.     - more robust X MIT-SHM support in X/Mesa
  387.     - glTexImage( format=GL_LUMINANCE ) didn't work
  388.     - GL_LINE mode polygons with line width > 1.0 could cause a crash
  389.     - numerous feedback bugs
  390.     - glReadPixels() from depth buffer was wrong
  391.     - error prone depth and stencil buffer allocation
  392.     New features:
  393.     - Preliminary Microsoft Windows driver
  394.     - Implemented a number of missing functions: glEvalCoord[12][df]v(),
  395.         glGet...(), etc.
  396.     - Added a few missing symbols to gl.h and glu.h
  397.     - Faster rendering of smooth-shaded, RGBA, depth-buffered polygons.
  398.     - Faster rendering of lines when width=2.0
  399.     - Stencil-related functions now work in display lists
  400.     Changes:
  401.     - renamed aux.h as glaux.h (MS-DOS names can't start with aux)
  402.     - most filenames are in 8.3 format to accomodate MS-DOS
  403.     - use GLubytes to store arrays of colors instead of GLints
  404.  
  405. Coming up...
  406.     All new triangle rasterization
  407.  
  408.  
  409.  
  410. Why is it the library called Mesa?
  411. ==================================
  412.  
  413. Why not?  More obvious names were considered but had to be rejected:
  414. FreeGL (too similar to the trademarked name OpenGL), Free3D (too similar
  415. to DEC's Open3D).  Also, I'm tired of acronyms.
  416.  
  417. [I've recently discovered that at least two other software products use the
  418. name Mesa.  A name change may be necessary in the future.  Suggestions are
  419. welcome!]
  420.  
  421.  
  422.  
  423. Thanks to
  424. =========
  425.  
  426. Erich Stefan Boleyn - for the glRotate code and testing early Mesa
  427. Joe Kiniry, Kendall Bennett - for opinions and discussion
  428. Marc Buffat - for the gluProject and gluUnproject functions
  429. Bernd Barsuhn, Volker Weiss - for the new implementation of evaluators
  430. Philip Brown - for the initial GLX, GLUT implementation
  431. Thorsten Ohl - for glXUseXFont() and glBitmap bug fixes
  432. Thomas Malik - for new invert_matrix and other xform.c code
  433. Michael Pichler - for X colormap code
  434. Thorsten Ohl, Jeroen van der Zijp - for the widget set
  435. Bob Mercier - for the new 8-bit RGB dithering code
  436. Pedro Vazquez - for establishing the Mesa mailing list
  437. Bogdan Sikorski - for the GLU polygon tesselation code
  438. Linas Vepstas - for his extrusion and swept surface library
  439. Frederic Devernay - for improved X shared memory support
  440. Asif Khan - for bringing _many_ subtle bugs to my attention
  441. Mark Peterson - for the MS Windows driver for Mesa
  442.  
  443.  
  444. Your contributionss are greatly appreciated!
  445.  
  446.  
  447.  
  448. This file last revised:  22 June 1995
  449.